home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / DELPHI32 / GRAPHICS / SCGRAPH / SCGRAPH.TXT < prev    next >
Text File  |  1996-11-11  |  20KB  |  542 lines
  1. TScGraph
  2. =============================================================
  3.  
  4.  
  5. About TScGraph
  6. --------------
  7.  
  8. TScGraph is a Delphi32 component for scientific/technical
  9. graphing of x/y-data.
  10.  
  11. The basis for this component was a graphing component
  12.  
  13.     txyGraph (version 1.0)
  14.  
  15. which was made available by
  16.  
  17.   Grahame Grieve, Biochemistry, St Vincent's Hospital
  18.   Victoria Parade, Fitzroy, 3065, Australia,
  19.   (g.grieve@pgrad.unimelb.edu.au),
  20.  
  21. which is gratefully acknowledged. Graham Grieve has done further 
  22. work; he has made version 2 of txyGraph available but TScGraph in its 
  23. basics has still many features of txyGraph (v. 1). 
  24.  
  25. This program is distributed as Freeware. You use it completely at 
  26. your own risk.  You may distribute this program in any manner, 
  27. as long as the following conditions are met:
  28.  
  29. 1) This file (ScGraph.txt) accompanies it, and is not modified.
  30. 2) No modifications are made to the units and code.
  31. 3) No fees are charged for the program.
  32. 4) If you wish to include this file in a collection of Freeware/Shareware
  33.    utilities, I would like a copy of that collection.
  34.  
  35.  
  36. Installation
  37. ------------
  38.  
  39. After copying to a suitable directory install as customary in Delphi32.
  40. From main menu drop down Component + Install and click the Add button.
  41. Find path and file name of where the TScGraph module (ScGraph.dcu) is 
  42. located. Click on OK. The component should now appear in a 'Graph' 
  43. folder within Delphi. Test it using the demo application.
  44.  
  45.  
  46. DISCLAIMER
  47. ----------
  48.  
  49. No warranty is given that the software or documentation is "error free"
  50. or meets any user's particular standards, requirements, or needs.
  51. Therefore, the author can not be made liable for any error or claims
  52. that arises directly or indirectly from the use of this software.
  53. The author is not responsible for any damage caused by using this
  54. component.
  55.  
  56.  
  57. Bugs
  58. ----
  59.  
  60. No fatal bugs are known to me for the time being in my environment
  61. (which is somewhat limited with respect to possible variations in
  62. hardware). 
  63.  
  64. Certainly the component still lacks some features or shows some 
  65. deficiencies (as any graphing component obviously always does).
  66. These are in particular:
  67.  
  68. - slow routines for drawing patterned lines, in particular
  69.   printing such graphs could result in long printing times.
  70.   Also dithering of colors in patterned lines could give poor
  71.   results in printing.
  72. - rather simple formatting of tick labels, no exponents
  73. - flashing of graph when refreshing
  74. - wasting memory with fixed data arrays
  75. - no error bars
  76. - yet no windows help file
  77. - etc.
  78.  
  79. Printing ScGraph with the method provided yields a practicable
  80. output with my printer (600dpi) but I am aware that in particular
  81. handling of font sizes for various printer resolutions is
  82. deficient and could result in inadequate font sizes.
  83.  
  84. If you find any bugs or have comments please mail to
  85.  
  86.   R.Nowotny@bmtp.akh-wien.ac.at
  87.  
  88.  
  89. Using this component
  90. --------------------
  91.  
  92. The appearance of the graph can be manipulated and viewed
  93. at design time. Data and plotting modes can only be added
  94. and viewed at run time. If a legend box is used only a
  95. placeholding box is displayed at design time.
  96.  
  97. Sizing of the plot box is adjusted automatically and depends
  98. on sizes of titles, legends, ticks and legends.
  99.  
  100. In 'Autometrics' mode, distances are not being given in pixels but 
  101. rather in units 1/1000 of the corresponding dimension of GraphPlot 
  102. (width or height) either on the screen or the printer canvas. 
  103. This results in proportional scaling of the graph when window sizes 
  104. (i.e. size of ScGraph) are changed or when printing.
  105.  
  106. For scaling the size of symbols and fonts the diagonal dimension is
  107. chosen as the reference length instead. The same applies to line
  108. width and line pattern length except for a line width equal to 0
  109. which gives always the thinnest possible line width (hair line)
  110. on screen or printer.
  111.  
  112. If 'Autometrics is set to false common Windows sizing is used.
  113.  
  114. The 'plotting' property turns plotting and refreshing of the
  115. graph on and off. In case lots of data are loaded into the
  116. data series or if many graph properties are changed it is
  117. a good idea to turn 'plotting' off.
  118.  
  119. It is the users duty to care for the range and size of data 
  120. added to the data series. The component does not raise 
  121. exceptions for negative values when log scales are used or 
  122. if data are out of range.
  123.  
  124.  
  125. Properties
  126. ----------
  127.  
  128.   Graphing Panel:
  129.     TScGraph: TCustomPanel;
  130.       Align,            BevelInner,          BevelOuter,
  131.       BevelWidth,       BorderStyle,         BorderWidth,
  132.       ctl3d,            cursor,              Color,
  133.       Height,           HelpContext,         Hint,
  134.       Left,             Name,                ParentColor,
  135.       ParentCtl3d,      ParentFont,          Tag,
  136.       Top,              visible,             Width
  137.         these are all inherited properties; seek Help in Delphi.
  138.  
  139.     MarginLeft,       MarginRight,
  140.     MarginTop,        MarginBottom
  141.       margins between the graphic panel border and and any graphical
  142.       component drawn on the ScGraph panel.
  143.  
  144.     Plotting
  145.       if true, the graph will be updated every time data and/or
  146.       properties are changed, if false, the name only will be shown.
  147.  
  148.     PlotColor
  149.       gives the color inside the plot box
  150.  
  151.     Autometrics
  152.       if true, margins and distances are automatically adjusted in 
  153.       relation to the resp. dimensions on screen or in print size,
  154.       for symbol sizes, font sizes and line widths the average of
  155.       horizontal and vertical size is taken for scaling.
  156.       if false, all units are used as defined in Windows/Delphi.
  157.  
  158.  
  159.   Graph title:
  160.     GraphTitle
  161.       Title    : if true, a Graph Title will be drawn
  162.       Caption  : title text string for GraphTitle
  163.       Distance : distance from title to the next graphical component below
  164.       Position : the horizontal position of the title is scaled from 0
  165.                  to 1000
  166.                       0: left border of text box coincides with the left
  167.                          border of the plot box
  168.                     500: centered horizontally
  169.                    1000: right border of text box coincides with the right
  170.                          border of the plot box
  171.  
  172.     GraphTitleFont: TFont;
  173.       Font for GraphTitle (see TFont object in Delphi)
  174.  
  175.  
  176.   Axes:
  177.     XAxis : TAxis;
  178.       properties for the (horizontal) x-axis
  179.  
  180.     YAxis : TAxis;
  181.       properties for the (vertical) y-axis
  182.  
  183.     TAxis object properties:
  184.       MajorTicks   : if true, major ticks are drawn
  185.       MajorTickLen : length of the major tickmarks
  186.       MajorTickWid : line width of the major tickmarks
  187.       MinorTicks   : if true, minor ticks are drawn
  188.       MinorTickLen : length of the minor tickmarks
  189.       MinorTickWid : line width of the minor tickmarks
  190.       TickPosition : position of the tickmarks
  191.                        tpOut   : tickmarks are drawn outside plot box
  192.                        tpCenter: tickmarks are centered on axis
  193.                        tpIn    : tickmarks are drawn inside plot box
  194.       TickLabels   : if true, labels are drawn next to each major tick
  195.       LabelDistance: gives the distance of the label text box from the
  196.                      tickmark
  197.       LabelAngle   : three directions for tick lables are available
  198.                        lr0  : horizontal
  199.                        lr90 : vertical (90 deg rotation)
  200.                        lr270: vertical (270 deg rotation)
  201.       LabelFormat  : format string for the label value. A Format String as
  202.                      explained in Delphi Help should be used.
  203.       Title        : if true, an axis title will be displayed
  204.       TitleText    : title text string
  205.       TitleDist    : distance of the title text box from tick labels or
  206.                      major ticks or axis, whatever is nearest
  207.       TitlePos     : the position of the axis title is scaled from 0 to
  208.                      1000 along the axis
  209.                        0   : leftmost/lowest position
  210.                        500 : centered
  211.                        1000: rightmost/top position
  212.       TitleAngle   : three directions for axis titles are available
  213.                        lr0  : horizontal
  214.                        lr90 : vertical (90 deg rotation)
  215.                        lr270: vertical (270 deg rotation)
  216.  
  217.     AxisPen: TPen;
  218.       Pen object properties for drawing of all axes
  219.  
  220.     AxisTitleFont: TFont;
  221.       Font for all axis titles
  222.  
  223.     Frame
  224.       if set true a frame is drawn around the plot box
  225.  
  226.     FramePen: TPen;
  227.       pen object properties for the plot box frame
  228.  
  229.     TickLabelFont: TFont;
  230.       font for all tick labels
  231.  
  232.  
  233.   Scales:
  234.     XScale: TScale;
  235.       properties for the scale on the x axis
  236.  
  237.     YScale: TScale;
  238.       properties for the scale on the y axis
  239.  
  240.     TScale object properties:
  241.       ScaleType      : sets the scale type
  242.                          stLin: linear scale
  243.                          stLog: logarithmic scale
  244.       Min            : minimum value on scale
  245.       Max            : maximum value on scale
  246.       MinRange       : minimum range on scale starting with Min
  247.       Intersection   : value on axis where the other axis intersects this
  248.                        axis, Min <= Intersction <= Max
  249.       LinStep        : LinStep gives the interval for major tick marks
  250.                        and major gridlines for a linear scale
  251.       MinorTickNumber: number of minor ticks per LinStep for a linear scale
  252.       MajorLogPattern: major ticks and grid lines are drawn for powers of
  253.                        ten. Additional major ticks and/or grid lines are
  254.                        drawn after setting an appropriate element ltxx out
  255.                        of (lt20, lt30, lt40, lt50, lt60, lt70, lt80, lt90)
  256.                        to true. Any combination is feasible.
  257.       MinorLogPattern: minor ticks and/or grid lines are drawn if appropriate
  258.                        elements stxx out of (st15, st20, st25, st30, st35,
  259.                        st40, st45, st50, st55, st60, st65, st70, st75, st80,
  260.                        st85, st90, st95) are set to true. Any combination is
  261.                        feasible.
  262.       AutoSizing     : if true, the values for Min/Max are recalculated
  263.                        when the graph is redrawn.
  264.       AutoStepping   : if true, the values for LinStep are recalculated
  265.                        when the min/max values change.
  266.  
  267.  
  268.   Grids:
  269.     GridHorizontal: TGrid;
  270.       provides properties for the horizontal major and minor grid
  271.  
  272.     GridVertical: TGrid;
  273.       provides properties for the vertical major and minor grid
  274.  
  275.     TGrid object properties:
  276.       MajorGrid     : if true a grid line will be drawn for each major
  277.                       tick on the appropriate axis
  278.       MajorGridColor: color of the major grid lines
  279.       MajorGridStyle: TPenStyle type
  280.       MinorGrid     : if true a grid line will be drawn for each minor
  281.                       tick on the appropriate axis
  282.       MinorGridColor: color of the minor grid lines
  283.       MinorGridStyle: TPenStyle type
  284.  
  285.  
  286.   Legends:
  287.     LegendBox
  288.       ShowLegends: if true, a legend box will be drawn
  289.       BoxColor   : color of the legend box background
  290.       BoxStyle   : brush for the legend box background
  291.       Framed     : if true, a frame will be drawn around the legend box
  292.       FrameColor : color of the legend box frame
  293.       FrameWidth : width of the legend box frame
  294.       Placement  : position of the legend box in the graph
  295.                      lbxTop      : outside the top border of the plot box
  296.                                    centered horizontally
  297.                      lbxRight    : outside the right border of the plot box
  298.                                    centered vertically
  299.                      lbxBottom   : outside the bottom border of the plot box
  300.                                    below axis and/or axis label centered
  301.                                    horizontally
  302.                      lbxNorthEast: top right within plot box
  303.                      lbxNorthWest: top left within plot box
  304.                      lbxSouthEast: bottom right within plot box
  305.                      lbxSouthWest: bottom left within plot box
  306.       Distance   : gives the distance(s) of the legend box border to the
  307.                    plot box border
  308.  
  309.     LegendFont   : TFont;
  310.       Font object for the legends
  311.  
  312.  
  313. Controlling the data series
  314. ---------------------------
  315.  
  316. In this version the number of data series is limited to 6 and
  317. number of data per series to 600.
  318.  
  319. Setting up a data series:
  320.  
  321.   procedure SetSeries(sN: integer; makeActive, Initialize: boolean;
  322.                       Color: TColor; Legend: shortstring);
  323.  
  324.     sN        : series number;  1 <= sN <= 6
  325.     makeActive: true/false turns display of series on/off
  326.     Initialize: true clears all data of series
  327.     Color     : defines color of lines, symbols and sticks
  328.                 associated with this series
  329.     Legend    : text string for the legend box
  330.  
  331.  
  332. Checking status of a series:
  333.  
  334.   function GetSeries(sN: integer; var Color: TColor;
  335.            var Legend: shortstring): boolean;
  336.  
  337.     returns false if not active
  338.  
  339.     sN        : determines the series
  340.     Color     : series color on return
  341.     Legend    : series legend on return
  342.  
  343.     see SetSeries for details
  344.  
  345.  
  346. Adding Data to the series:
  347.  
  348.   function AddPoint(sN: integer; x, y: double): boolean;
  349.  
  350.     returns true if the data were successfully added
  351.  
  352.     sN        : number of series to which data are to be added
  353.     x, y      : data point to add. Only one single data point is
  354.                 accepted for each value of x.
  355.  
  356.  
  357. Delete a single data point:
  358.  
  359.   function DeletePoint(sN: integer; x: double): boolean;
  360.  
  361.     returns true if data point was succesfully deleted.
  362.  
  363.     sN        : number of series from which a data point is to be
  364.                 deleted.
  365.                 If sN = 0, all active series are checked for x
  366.                 values.
  367.     x         : x value of the data point to delete.
  368.  
  369.  
  370. Find a data point for a given x-value:
  371.  
  372.   function GetPoint(sN: integer; var x, y: double): boolean;
  373.  
  374.     returns true if a data point was found
  375.  
  376.     sN        : number of series for point search
  377.     x, y      : x-value of point
  378.  
  379.  
  380. Deleting all data of a series:
  381.  
  382.   procedure ClearSeries(sN: integer);
  383.  
  384.     sN        : number of series to be cleared, the status of the
  385.                 series remains unchanged. Data can also be cleared
  386.                 by SetSeries setting both makeActive and Initialize
  387.                 to true.
  388.                 If sN = 0, all series are cleared.
  389.  
  390.  
  391. Plotting lines:
  392.  
  393.   procedure SetSeriesLine(sN: integer; Status: boolean;
  394.               Mode: pmPlotMode; LWidth: integer; LStyle: TPenStyle);
  395.  
  396.     sN        : determines the series
  397.     Status    : a line will be drawn if true
  398.     Mode      : plot mode of type
  399.                   pmLine   : straight line connecting the points
  400.                   pmHisto  : histogram line
  401.                   pmSticks : draws sticks from the X-axis to the point
  402.     LWidth    : line width given in 1/1000 of graph diameter.
  403.                 For LWidth = 0 a hair line will always be drawn.
  404.     LStyle    : line style
  405.                   psSolid  : solid line
  406.                   psDash   : dashed line
  407.                   psDot    : dotted line
  408.                   psDashDot: alternating dashes and dots
  409.                   psDashDotDot: series of dash-dot-dot combinations
  410.  
  411.  
  412. Retrieving line settings:
  413.  
  414.   function GetSeriesLine(sN: integer; var Mode: pmPlotMode;
  415.              var LWidth: integer; var LStyle: TPenStyle): boolean;
  416.  
  417.     result is equal to status of line drawing
  418.  
  419.     sN        : determines the series
  420.     Mode      : returns plot mode, see SetSeriesLine
  421.     LWidth    : returns line width
  422.     LStyle    : returns line style
  423.  
  424.     see SetSeriesLine for details
  425.  
  426.  
  427. Plotting symbols:
  428.  
  429.   procedure SetSeriesPoints(sN: integer; Status: boolean;
  430.                   Shape: etPointShape; Size: integer);
  431.  
  432.     sN        : determines the series
  433.     Status    : symbols for data points will be drawn if true
  434.     Shape     : symbol shape of type
  435.                   psCross        : Diagonal cross
  436.                   psHCross       : Hatched cross
  437.                   psSquare       : hollow square
  438.                   psSquareFilled : filled square
  439.                   psDiamond      : hollow diamond
  440.                   psDiamondFilled: filled diamond
  441.                   psCircle       : hollow circle
  442.                   psCircleFilled : filled circle
  443.                   psTriangleUp   : hollow triangle pointing upwards
  444.                   psTriangleUpFilled: filled triangle pointing upwards
  445.                   psTriangleDown : hollow triangle pointing downwards
  446.                   psTriangleDownFilled: filled triangle pointing downwards
  447.     Size      : size of the symbol given by the size of the
  448.                 circumscribing square in 1/1000 units of graph diameter.
  449.  
  450.  
  451. Retrieving point settings:
  452.  
  453.   function GetSeriesPoints(sN: integer; var Size: integer;
  454.                 var Shape: etPointShape): boolean;
  455.  
  456.     result is equal to status of symbol drawing
  457.  
  458.     sN        : determines the series
  459.     Size      : symbol size
  460.     Shape     : symbol shape
  461.  
  462.     see SetSeriesPoints for details
  463.  
  464.  
  465. Run time mouse routines
  466. -----------------------
  467.  
  468.   function GetMouseX(x: integer): double;
  469.  
  470.     returns the scaled value given by the X-scale for a given mouse
  471.     position x given in pixels
  472.  
  473.   function GetMouseY(y: integer): double;
  474.  
  475.     returns the scaled value given by the Y-scale for a given mouse
  476.     position y given in pixels
  477.  
  478.   function GetMouseVals(sN, x: integer; var xVal, yVal: double): boolean;
  479.  
  480.     Retrieves the value of the data point matching the mouse point
  481.     given by its x position best.
  482.     Function returns true if successful, or false if the mouse is
  483.     outside the plot area.
  484.  
  485.     sN       : series number
  486.     x        : mouse x position in pixels
  487.     xVal     : scaled x value of data point
  488.     yVal     : scaled y value of data point
  489.  
  490.   function GetMouseXY(Sn, x, y: integer; var xbyscale, ybyscale,
  491.                 xbyPoint, ybyPoint: double): boolean;
  492.  
  493.     Calculates scaled values for mouse position x/y and retrieves
  494.     the value of the data point matching the mouse point best
  495.     with regard to its x position.
  496.     Function returns true if successful, or false if the mouse is
  497.     outside the plot area.
  498.  
  499.     sN       : series number
  500.     x, y     : mouse x and y position in pixels
  501.     xbyscale : scaled x value of data point
  502.     ybyscale : scaled y value of data point
  503.     xbyPoint : scaled x value of nearest data point in series
  504.     ybyPoint : scaled y value of nearest data point in series
  505.  
  506.  
  507. Printing of the graph
  508. ---------------------
  509.  
  510.   procedure PrintGraph(LeftMM, TopMM, WidthMM, HeightMM: longint);
  511.  
  512.     prints the graph on the current windows printer.
  513.  
  514.     LeftMM   : distance of the left topmost corner of the graph from
  515.                left edge of the paper in mm, if < 0 the graph is
  516.                centered horizontally
  517.     TopMM    : distance of the left topmost corner of the graph from
  518.                the top edge of the paper in mm, if < 0 the graph is
  519.                centered vertically
  520.     WidthMM  : width of the graph in mm, if < 0 the full printing
  521.                width of the paper is used
  522.     HeightMM : height of the graph in mm, if < 0 the full printing
  523.                height of the paper is used
  524.  
  525.   'Autometrics' should be set to true as this gives adequate scaling 
  526.    of sizes and better results.
  527.  
  528.  
  529. Copying to the clipboard
  530. ------------------------
  531.  
  532.   procedure CopyGraphToClipboard;
  533.  
  534.     copies the graph as a bitmap to the windows clipboard so that
  535.     the graph could be used in other windows applications.
  536.  
  537.  
  538. Enjoy,
  539.  
  540. Robert Nowotny
  541. R.Nowotny@bmtp.akh-wien.ac.at
  542.